home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / spwno413.zip / SPAWNO.DOC < prev    next >
Text File  |  1992-12-12  |  22KB  |  487 lines
  1. SPAWNO v4.13   12/12/91   disk/EMS/XMS/INT15 swapping replacement for spawn()
  2. (c) Copyright 1990,1991,1992 Ralf Brown.  All Rights Reserved.
  3.  
  4.  
  5. -----------------
  6. LICENSE
  7.  
  8. This document and the associated header file, libraries, and source and
  9. object modules may be freely copied provided that:
  10.      1) all of the files are copied as a group (such as in a single
  11.     archive).  See below for a list of files.
  12.      2) the files are not modified in any way (including removal or
  13.     alteration of copyright notices or this license)
  14.      3) no charge beyond a cost-recovery fee not to exceed $5, or a
  15.     general telecommunications connection fee, is made
  16.  
  17. The source and/or object code comprising the public SPAWNO distribution
  18. may be incorporated at no charge into programs which are distributed or
  19. sold to others provided that:
  20.      1) credit is given in the documentation.  A mention such as
  21.        "This product uses the SPAWNO routines by Ralf Brown
  22.         to minimize memory use while shelling to DOS and
  23.         running other programs."
  24.     is sufficient.
  25.      2) you drop me a line telling me that you are using SPAWNO and
  26.     in which product(s) you are using it (see addresses at the
  27.     end of this file).  I'm interested in finding out how wide-
  28.     spread the use of SPAWNO becomes.
  29.  
  30.  
  31. -----------------
  32. DISCLAIMER
  33.  
  34. Although both I and others have tested the code which comprises SPAWNO,
  35. it is entirely possible that SPAWNO may malfunction in environments or
  36. under circumstances in which it has not been tested.  This code is
  37. provided AS IS, and the author disclaims any and all responsibility for
  38. damages (both consequential and incidental) resulting from the use or
  39. misuse of SPAWNO.  Sole responsibility for determining the suitability
  40. of the code rests with the user.
  41.  
  42.  
  43. -----------------
  44. FILES
  45.  
  46. The disk or archive you received should contain the following files:
  47.  
  48.     SPAWNO.DOC    this file
  49.     SPAWNO.H    the header file providing prototypes for the functions
  50.     SPAWNx.LIB    versions of the library for each of [T]iny, [S]mall,
  51.             [C]ompact, [M]edium, [L]arge, and [H]uge memory
  52.             models.
  53.     SPAWNTP.OBJ    Turbo Pascal version of SPAWNO
  54.     SPAWNO.PAS    Turbo Pascal unit encapsulating SPAWNO
  55.     SPAWN_MS.ZIP    Microsoft C versions of compiler-specific functions
  56.     MSC.BAT        replace Turbo C specific functions in libraries with
  57.             Microsoft C versions.
  58.     NOREPLAC.BAT    remove replacements for the standard spawn..()
  59.             functions from the libraries.
  60.     SWAPTEST.C    example program for testing
  61.     TEST.PAS    example program for testing
  62.     SOURCE.ZIP    archive containing partial source code for SPAWNO
  63.         _SPAWNO.H        header file for recompiling library
  64.         *.C            source for the spawn..() and spawn...o() functions
  65.         RULES.ASI        shortened and modified Turbo C macro file
  66.         SPAWNO.INC        include file for various important constants
  67.         SPAWNPTH.ASM    source for the path search
  68.         CHECKEXT.ASM    check for 'file', 'file.EXE', and 'file.COM'
  69.         SWAP_EMS.ASM    support routines for swapping to EMS
  70.         SWAPLIST.ASM    specify which swap types will be linked in
  71.         SPAWNENV.ASM    make an environment block from an array of strings     
  72.         SPAWNERR.ASM    set _doserrno and errno
  73.         MAKEFILE
  74.  
  75.  
  76. -----------------
  77. WHAT'S NEW
  78.  
  79. Changes/fixes from versions 4.00 to 4.10:
  80.     Now swaps to disk with non-NULL swap list in large-data memory models
  81.     Now correctly deletes swap file if child program changes directories
  82.     If the given program name is "FOO", and both "FOO" and either
  83.        "FOO.COM" and/or "FOO.EXE" exist in the same directory, it will
  84.        now execute either "FOO.COM" or "FOO.EXE" rather than "FOO", as
  85.        both version 4.00 and the Borland library functions do.  To
  86.        execute "FOO", pass "FOO." rather than just "FOO" to the function.
  87.     Fixed bug which may have led to a partially corrupted environment
  88.        in a few circumstances
  89. Changes/fixes since version 4.10:
  90.     Fixed bug which caused the PSP to restore incorrectly after a spawn
  91.        when DS != SS.
  92.     Fixed bug introduced in v4.10 which caused a crash on return from the
  93.        child program if there was insufficient disk space for the swap
  94.        file.
  95.     Fixed error in va_start call in various *.C files.  This problem
  96.        results in compile-time errors when compiling under BC++ in
  97.        certain modes (but the code compiled without warnings under
  98.        Turbo C 2.0).
  99.  
  100. -----------------
  101. INSTALLATION
  102.  
  103. If you are using Turbo C, Turbo C++, or Borland C++, simply dearchive
  104. the libraries and header file and place them where your compiler can
  105. find them.  If you are using Microsoft C, dearchive SPAWN_MS.ZIP and
  106. then run the MSC batch file to replace the compiler-specific functions
  107. in the libraries with Microsoft C versions.  Please do not run this
  108. batch file on your original copy of the libraries.
  109.  
  110. If you are using Turbo Pascal, unarchive SPAWNTP.OBJ and SPAWNO.PAS.
  111. Compile SPAWNO.PAS and then add a USES SPAWNO; line to your program.
  112. After that you can call the function SPAWN() as desired.  The
  113. distribution does not contain a pre-compiled version because .TPU
  114. files are not compatible between different versions of Turbo Pascal.
  115.  
  116.  
  117. -----------------
  118. INSTRUCTIONS
  119.  
  120. As distributed, SPAWNO contains replacements for the standard spawn..()
  121. functions.  You can use SPAWNO with absolutely no changes to your
  122. existing source code; however, you will probably want to call
  123. init_SPAWNO() from main(), and include SPAWNO.H for that source file.
  124. The initialization function takes two arguments: the first is a string
  125. containing a list of directories (separated by semicolons) in which to
  126. attempt to store the swap file when swapping to disk. The second
  127. specifies which swap devices to attempt to use; it may be either
  128. SWAP_ANY or the ORing or addition of any combination of SWAP_DISK,
  129. SWAP_EMS, SWAP_EXT, and SWAP_XMS (such as SWAP_DISK|SWAP_XMS).    If you
  130. do not call init_SPAWNO(), the defaults are to attempt all swap devices
  131. and to store the swap file in the current directory when swapping to
  132. disk.  init_SPAWNO() will set the swap file directory list to the first
  133. of the following to have a non-NULL, non-empty value: the environment
  134. variable SWAPDIR, the passed parameter, the environment variable TEMP,
  135. and the environment variable TMP.  Note that init_SPAWNO is the only
  136. function in the library which uses these environment variables.
  137.  
  138. After making the above change, recompile your existing code, but include
  139. the SPAWNO library in the link step.  Note that SPAWNO does not support
  140. the P_OVERLAY spawn type--any calls using that argument should be
  141. replaced with the corresponding exec..() function.  If a SPAWNO function
  142. is called with P_OVERLAY, it simply returns an error.
  143.  
  144. For backwards compatibility with previous versions of SPAWNO, and for
  145. those who (for whatever reason) require the use of both the swapping and
  146. standard spawn..() functions, there is a second set of functions which
  147. take an explicit swap directory argument.  To use them, include the
  148. header file SPAWNO.H.  Then use the functions provided in this
  149. archive--spawnvo(), spawnlo(), spawnvpo(), etc--as you would the
  150. corresponding spawnv(), spawnl(), etc, except replace the first argument
  151. by a string containing the path where the swap file is to be stored.
  152. Note that the swap file path is required even when swapping to XMS, EMS,
  153. or plain extended memory, as SPAWNO will swap to disk anyway if there is
  154. not enough memory available.
  155.  
  156. If you require the use of both the swapping and standard spawn..()
  157. functions, you will need to run the NOREPLAC.BAT batch file to remove
  158. the modules containing the replacements for the standard functions or
  159. arrange the linker command line such that SPAWNx.LIB is listed after the
  160. standard runtime library (for Turbo/Borland C users, the latter requires
  161. a separate TLINK command, as TCC/BCC places any libraries specified on
  162. the command line prior to the runtime library).     Please do not run
  163. NOREPLAC on your original copy of the libraries, as the process is
  164. destructive and cannot be reversed.
  165.  
  166. The spawn?p??() functions search for both .COM and .EXE files in the
  167. current directory and then in the pathed